/*
 * $Id$ S.O.D.A. - Simple Object Database Access
 */
package kevin.study.zephyr.domain.soda;

/**
 * constraint to limit the objects returned upon
 * <br>
 * Constraints are constructed by calling
 * {@link Query#constrain Query.constrain()}. <br>
 * <br>
 * Constraints can be joined with the methods {@link #and and()} and
 * {@link #or or()}. <br>
 * <br>
 * The methods to modify the constraint evaluation algorithm may be merged, to
 * construct combined evaluation rules. Examples:
 * <ul>
 * <li> <code>Constraint#smaller().equal()</code> for "smaller or equal" </li>
 * <li> <code>Constraint#not().like()</code> for "not like" </li>
 * <li> <code>Constraint#not().greater().equal()</code> for "not greater or
 * equal" </li>
 * </ul>
 * Modify by Kevin.Huang 2007-09-30 除出iidentity
 */
public interface Constraint {

	/**
	 * links two Constraints for AND evaluation.
	 * 
	 * @param with
	 *            the other {@link Constraint}
	 * @return a new {@link Constraint}, that can be used for further calls to
	 *         {@link #and and()} and {@link #or or()}
	 */
	Constraint and(Constraint with);

	/**
	 * links two Constraints for OR evaluation.
	 * 
	 * @param with
	 *            the other {@link Constraint}
	 * @return a new {@link Constraint}, that can be used for further calls to
	 *         {@link #and and()} and {@link #or or()}
	 */
	Constraint or(Constraint with);

	/**
	 * sets the evaluation mode to <code>==</code>.
	 * 
	 * @return this {@link Constraint} to allow the chaining of method calls.
	 */
	Constraint equal();

	/**
	 * sets the evaluation mode to <code>&gt;</code>.
	 * 
	 * @return this {@link Constraint} to allow the chaining of method calls.
	 */
	Constraint greater();

	/**
	 * sets the evaluation mode to <code>&lt;</code>.
	 * 
	 * @return this {@link Constraint} to allow the chaining of method calls.
	 */
	Constraint smaller();

	/**
	 * sets the evaluation mode to "like" comparison.
	 * 
	 * @return this {@link Constraint} to allow the chaining of method calls.
	 */
	Constraint like();

	/**
	 * 是否以此开始
	 * 
	 * @param caseSensitive
	 *            是否大小写敏感
	 * @return
	 */
	Constraint startsWith(boolean caseSensitive);

	/**
	 * 是否以此结束
	 * 
	 * @param caseSensitive
	 *            是否大小写敏感
	 * @return
	 */
	Constraint endsWith(boolean caseSensitive);

	/**
	 * sets the evaluation mode to containment comparison. <br>
	 * <br>
	 * Evaluation is dependant on the constrained query node:
	 * <dl>
	 * <dt><code>String</code></dt>
	 * <dd>the persistent object is tested to contain a substring.</dd>
	 * <dt>arrays, {@linkplain java.util.Collection collections}</dt>
	 * <dd>the persistent object is tested to contain all elements of the
	 * constraining object.
	 * </dl>
	 * 
	 * @return this {@link Constraint} to allow the chaining of method calls.
	 */
	Constraint contains();

	/**
	 * turns on not() comparison.
	 * 
	 * @return this {@link Constraint} to allow the chaining of method calls.
	 */
	Constraint not();

	/**
	 * returns the Object the query graph was constrained with to create this
	 * {@link Constraint}.
	 * 
	 * @return Object the constraining object.
	 */
	Object getObject();

}
